What is @csstools/postcss-progressive-custom-properties?
@csstools/postcss-progressive-custom-properties is a PostCSS plugin that allows you to progressively enhance your CSS custom properties (variables). It enables you to use custom properties in a way that provides fallbacks for older browsers that do not support them, ensuring a smoother transition and better compatibility.
What are @csstools/postcss-progressive-custom-properties's main functionalities?
Progressive Enhancement of Custom Properties
This feature allows you to define custom properties and use them in your CSS. The plugin will automatically add fallback values for browsers that do not support custom properties.
/* Input CSS */
:root {
--main-color: #3498db;
}
body {
color: var(--main-color);
}
/* Output CSS */
:root {
--main-color: #3498db;
}
body {
color: #3498db;
color: var(--main-color);
}
Custom Property Fallbacks
This feature allows you to specify fallback values for custom properties. The plugin ensures that the fallback value is used in browsers that do not support custom properties.
/* Input CSS */
:root {
--padding: 10px;
}
.container {
padding: var(--padding, 20px);
}
/* Output CSS */
:root {
--padding: 10px;
}
.container {
padding: 20px;
padding: var(--padding, 20px);
}
Other packages similar to @csstools/postcss-progressive-custom-properties
postcss-custom-properties
postcss-custom-properties is a PostCSS plugin that transforms W3C CSS Custom Properties for cascading variables. It provides similar functionality to @csstools/postcss-progressive-custom-properties by enabling the use of custom properties with fallbacks for older browsers. However, it may not offer the same level of progressive enhancement.
postcss-preset-env
postcss-preset-env is a PostCSS plugin that allows you to use future CSS features today. It includes support for custom properties and provides fallbacks for older browsers. Compared to @csstools/postcss-progressive-custom-properties, it offers a broader range of CSS features beyond just custom properties.
PostCSS Progressive Custom Properties ![PostCSS](https://postcss.github.io/postcss/logo.svg)
![Discord](https://shields.io/badge/Discord-5865F2?logo=discord&logoColor=white)
PostCSS Progressive Custom Properties is a utility plugin to correctly declare Custom Property fallbacks and enhancements.
[!WARNING]
It is not intended to be used directly by stylesheet authors.
Meant to be included in other PostCSS plugins that provide CSS value transforms as fallbacks.
Custom Properties are not discarded like regular declarations when invalid.
This makes it tricky to provide fallback values for older browsers.
The solution is to wrap Custom Property declarations in an @supports
rule.
:root {
/* fallback */
--a-color: red;
/* progressive enhancement */
--a-color: oklch(40% 0.234 0.39 / var(--opacity-50));
}
/* becomes */
:root {
--a-color: red;
}
@supports (color: oklch(0% 0 0)) {
:root {
--a-color: oklch(40% 0.234 0.39 / var(--opacity-50));
}
}
Ignored values
initial
and <white space>
are ignored.
.initial {
--prop-1: red;
--prop-1: initial;
}
.white-space {
--prop-1: red;
--prop-1:;
--prop-2: red;
--prop-2: ;
--prop-3: red;
--prop-3: ;
}
/* remains */
.initial {
--prop-1: red;
--prop-1: initial;
}
.white-space {
--prop-1: red;
--prop-1:;
--prop-2: red;
--prop-2: ;
--prop-3: red;
--prop-3: ;
}
Usage
Add PostCSS Progressive Custom Properties to your project:
npm install @csstools/postcss-progressive-custom-properties --save-dev
Use PostCSS Progressive Custom Properties as a PostCSS plugin:
const postcss = require('postcss');
const postcssCustomProperties = require('@csstools/postcss-progressive-custom-properties');
postcss([
postcssProgressiveCustomProperties()
]).process(YOUR_CSS );
@supports
This plugin wraps Custom Property override declarations in an @supports
rule.
With PostCSS 8 this trigger declaration visitors to run again.
Make sure your plugin detects and ignores values inside relevant @supports
rules.
Reading list
PostCSS Progressive Custom Properties runs in all Node environments, with special instructions for: